<!DOCTYPE html>
<html lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GCC Coding Conventions</title>
<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
</head>

<body>
<h1>GCC Coding Conventions</h1>

<p>There are some additional coding conventions for code in GCC,
beyond those in the <a href="https://www.gnu.org/prep/standards/">GNU
Coding Standards</a>.  Some existing code may not follow these conventions,
but they must be used for new code.  If changing existing
code to follow these conventions, it is best to send changes to follow
the conventions separately from any other changes to the code.</p>

<ul>
<li><a href="#Documentation">Documentation</a></li>
<li><a href="#ChangeLogs">ChangeLogs</a></li>
<li><a href="#Portability">Portability</a></li>
<li><a href="#Makefiles">Makefiles</a></li>
<li><a href="#Testsuite">Testsuite Conventions</a></li>
<li><a href="#Diagnostics">Diagnostics Conventions</a></li>
<li><a href="#Spelling">Spelling, terminology and markup</a></li>
<li><a href="#CandCxx">C and C++ Language Conventions</a>
    <ul>
    <li><a href="#C_Options">Compiler Options</a></li>
    <li><a href="#C_Language">Language Use</a>
        <ul>
        <li><a href="#Assertions">Assertions</a></li>
        <li><a href="#Character">Character Testing</a></li>
        <li><a href="#Error">Error Node Testing</a></li>
        <li><a href="#Generated">Parameters Affecting Generated Code</a></li>
        <li><a href="#C_Inlining">Inlining Functions</a></li>
        </ul>
    </li>
    <li><a href="#C_Formatting">Formatting Conventions</a>
        <ul>
        <li><a href="#Line">Line Length</a></li>
        <li><a href="#C_Names">Names</a></li>
        <li><a href="#Expressions">Expressions</a></li>
        </ul>
    </li>
    </ul>
</li>
<li><a href="#Cxx_Conventions">C++ Language Conventions</a>
    <ul>
    <li><a href="#Cxx_Language">Language Use</a>
        <ul>
        <li><a href="#Variable">Variable Definitions</a></li>
        <li><a href="#Struct_Use">Struct Definitions</a></li>
        <li><a href="#Class_Use">Class Definitions</a></li>
        <li><a href="#Constructors">Constructors and Destructors</a></li>
        <li><a href="#Conversions">Conversions</a></li>
        <li><a href="#Over_Func">Overloading Functions</a></li>
        <li><a href="#Over_Oper">Overloading Operators</a></li>
        <li><a href="#Default">Default Arguments</a></li>
        <li><a href="#Cxx_Inlining">Inlining Functions</a></li>
        <li><a href="#Template_Use">Templates</a></li>
        <li><a href="#Namespace_Use">Namespaces</a></li>
        <li><a href="#RTTI">RTTI and <code>dynamic_cast</code></a></li>
        <li><a href="#Casts">Other Casts</a></li>
        <li><a href="#Exceptions">Exceptions</a></li>
        <li><a href="#Standard_Library">The Standard Library</a></li>
        </ul>
    </li>
    <li><a href="#Cxx_Formatting">Formatting Conventions</a>
        <ul>
        <li><a href="#Cxx_Names">Names</a></li>
        <li><a href="#Struct_Form">Struct Definitions</a></li>
        <li><a href="#Class_Form">Class Definitions</a></li>
        <li><a href="#Member_Form">Class Member Definitions</a></li>
        <li><a href="#Template_Form">Templates</a></li>
        <li><a href="#ExternC">Extern "C"</a></li>
        <li><a href="#Namespace_Form">Namespaces</a></li>
        </ul>
    </li>
    </ul>
</li>
</ul>


<h2 id="Documentation">Documentation</h2>

<p>Documentation, both of user interfaces and of internals, must be
maintained and kept up to date.  In particular:</p>

<ul>

  <li>All command-line options (including all <code>--param</code>
  arguments) must be documented in the GCC manual.</li>

  <li>Any change to documented behavior (for example, the behavior of
  a command-line option or a GNU language extension) must include the
  necessary changes to the manual.</li>

  <li>All target macros must be documented in the GCC manual.</li>

  <li>The documentation of the <code>tree</code> and RTL data
  structures and interfaces must be kept complete and up to date.</li>

  <li>In general, the documentation of all documented aspects of the
  front-end and back-end interfaces must be kept up to date, and the
  opportunity should be taken where possible to remedy gaps in or
  limitations of the documentation.</li>

</ul>


<h2 id="ChangeLogs">ChangeLogs</h2>

<p>
ChangeLog entries are part of git commit messages and are automatically put
into a corresponding ChangeLog file.  A ChangeLog template can be easily generated
with <code>./contrib/mklog.py</code> script.  GCC offers a checking script that
verifies a proper ChangeLog formatting (see <code>git gcc-verify</code> git alias).
for a particular git commit.  The checking script covers most commonly used ChangeLog
formats and the following paragraphs explain what it supports.
</p>

<p>See also what the <a
href="http://www.gnu.org/prep/standards_toc.html">GNU Coding
Standards</a> have to say about what goes in ChangeLogs; in
particular, descriptions of the purpose of code and changes should go
in comments rather than the ChangeLog, though a single line overall
description of the changes may be useful above the ChangeLog entry for
a large batch of changes.</p>

<h3>Components</h3>

<ul>
    <li><code>git_description</code> - a leading text with git commit description</li>
    <li><code>committer_timestamp</code> - line with timestamp and an author name and email (2 spaces before and after name) <br>
        example: <code>2020-04-23␣␣Martin Liska␣␣&lt;mliska@suse.cz&gt;</code></li>
    <li><code>additional_author</code> - line with additional commit author name and email (starting with a tabular and 4 spaces) <br>
        example: <code>\t␣␣␣␣Martin Liska␣␣&lt;mliska@suse.cz&gt;</code></li>
    <li><code>changelog_location</code> - a location to a ChangeLog file <br>
        supported formats: <code>a/b/c/ChangeLog</code>, <code>a/b/c/ChangeLog:</code>, <code>a/b/c/</code> (where ChangeLog file lives in the folder), <code>\ta/b/c/</code> and <code>a/b/c</code></li>
    <li><code>pr_entry</code> - bug report reference <br>
        example: <code>\tPR component/12345</code></li>
    <li><code>changelog_file</code> - a modified file mentined in a ChangeLog:
        supported formats: <code>\t* a/b/c/file.c:</code>, <code>\t* a/b/c/file.c (function):</code>, <code>\t* a/b/c/file1.c, a/b/c/file2.c:</code></li>
    <li><code>changelog_file_comment</code> - line that follows a <code>changelog_file</code> with description of changes in the file;
        must start with <code>\t</code></li>
    <li><code>co_authored_by</code> - <a
        href="https://docs.github.com/en/github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors">GitHub format</a>
        for a Co-Authored-By</li>
</ul>

<h3>Format rules</h3>

<ul>
    <li><code>git_description</code> - optional; ends right before one of the other compoments is found</li>
    <li><code>committer_timestamp</code> - optional; when found before a <code>changelog_file</code>, then it is added
    to each changelog entry</li>
    <li><code>additional_author</code> - optional</li>
    <li><code>changelog_location</code> - optional; parser attempts to identify ChangeLog file based
    on modified files; <code>$changelog_location</code> belonging to a different ChangeLog must
    be separated with an empty line</li>
    <li><code>pr_entry</code> - optional; can contain any number of PR entries</li>
    <li><code>changelog_file</code> - each <code>changelog_location</code> must contain at least one file</li>
    <li><code>changelog_file_comment</code> - optional</li>
    <li><code>co_authored_by</code> - optional, can contain more than one</li>
</ul>

<h3>Documented behaviour</h3>

<ul>
    <li>a missing <code>changelog_location</code> file location can be deduced based on group of <code>changelog_file</code>s</li>
    <li>script automatically generates missing "New file." entries for files that are added in a commit</li>
    <li>changed files that are not mentioned in a ChangeLog file generate an error</li>
    <li>similarly for unchanged files that are mentioned in a ChangeLog file</li>
    <li>a commit author and committer date stamp can be automatically deduced from a git commit
        (additional authors are taken from Co-Authored-By trailer) - we recommend to use it</li>
    <li><code>co_authored_by</code> is added to each ChangeLog entry</li>
    <li>a PR component is checked against list of valid components</li>
    <li><code>ChangeLog</code> files, <code>DATESTAMP</code>, <code>BASE-VER</code> and <code>DEV-PHASE</code> can be modified only separately from other files</li>
</ul>

<h3>Example patch</h3>

<pre><code>This patch adds a second movk pattern that models the instruction
as a "normal" and/ior operation rather than an insertion.  It fixes
the third insv_1.c failure in PR87763, which was a regression from
GCC 8.

2020-02-06  John Foo  &lt;john@example.com&gt;

gcc/
	PR target/87763
	* config/aarch64/aarch64-protos.h (aarch64_movk_shift): Declare.
	* config/aarch64/aarch64.c (aarch64_movk_shift): New function.
	* config/aarch64/aarch64.md (aarch64_movk&lt;mode&gt;): New pattern.

gcc/testsuite/
	PR target/87763
	* gcc.target/aarch64/movk_2.c: New test.

Co-Authored-By: Jack Bar  &lt;jack@example.com&gt;
</code></pre>

<h3>Tokenized patch</h3>

<pre>
<code>$git_description

$committer_timestamp

$changelog_location
$pr_entry
$changelog_file
$changelog_file
$changelog_file

$changelog_location
$pr_entry
$changelog_file

$co_authored_by</code>
</pre>

<h2 id="Portability">Portability</h2>

<p>There are strict requirements for portability of code in GCC to
older systems whose compilers do not implement all of the
latest ISO C and C++ standards.
</p>

<p>
The directories
<code>gcc</code>, <code>libcpp</code> and <code>fixincludes</code>
may use C++03.
They may also use the <code>long long</code> type
if the host C++ compiler supports it.
These directories should use reasonably portable parts of C++03,
so that it is possible to build GCC with C++ compilers other than GCC itself. 
If testing reveals that
reasonably recent versions of non-GCC C++ compilers cannot compile GCC,
then GCC code should be adjusted accordingly.
(Avoiding unusual language constructs helps immensely.)
Furthermore,
these directories <em>should</em> also be compatible with C++11.
</p>

<p>
The directories libiberty and libdecnumber must use C
and require at least an ANSI C89 or ISO C90 host compiler.
C code should avoid pre-standard style function definitions, unnecessary
function prototypes and use of the now deprecated <code>PARAMS</code> macro.
See <a
href="https://gcc.gnu.org/svn/gcc/trunk/gcc/README.Portability">README.Portability</a>
for details of some of the portability problems that may arise.  Some
of these problems are warned about by <code>gcc -Wtraditional</code>,
which is included in the default warning options in a bootstrap.
</p>

<p>The programs included in GCC are linked with the
libiberty library, which will replace some standard
library functions if not present on the system used, so those
functions may be freely used in GCC.  In particular, the ISO C string
functions <code>memcmp</code>, <code>memcpy</code>,
<code>memmove</code>, <code>memset</code>, <code>strchr</code> and
<code>strrchr</code> are preferred to the old functions
<code>bcmp</code>, <code>bcopy</code>, <code>bzero</code>,
<code>index</code> and <code>rindex</code>; see messages <a
href="https://gcc.gnu.org/ml/gcc/1998-09/msg01000.html">1</a> and <a
href="https://gcc.gnu.org/ml/gcc/1998-09/msg01127.html">2</a>.  The
older functions must no longer be used in GCC; apart from
<code>index</code>, these identifiers are poisoned to prevent their
use.</p>

<p>Machine-independent files may contain conditionals on features of a
particular system, but should never contain conditionals such as
<code>#ifdef __hpux__</code> on the name or version of a particular
system.  Exceptions may be made to this on a release branch late in
the release cycle, to reduce the risk involved in fixing a problem
that only shows up on one particular system.</p>

<p>Function prototypes for extern functions should only occur in
header files.  Functions should be ordered within source files to
minimize the number of function prototypes, by defining them before
their first use.  Function prototypes should only be used when
necessary, to break mutually recursive cycles.</p>

<h2 id="Makefiles">Makefiles</h2>

<p><code>touch</code> should never be used in GCC Makefiles.  Instead
of <code>touch foo</code> always use <code>$(STAMP) foo</code>.</p>


<h2 id="Testsuite">Testsuite Conventions</h2>

<p>Every language or library feature, whether standard or a GNU
extension, and every warning GCC can give, should have testcases
thoroughly covering both its specification and its implementation.
Every bug fixed should have a testcase to detect if the bug
recurs.</p>

<p>The testsuite READMEs discuss the requirement to use <code>abort
()</code> for runtime failures and <code>exit (0)</code> for success.
For compile-time tests, a trick taken from autoconf may be used to evaluate
expressions: a declaration <code>extern char x[(EXPR) ? 1 :
-1];</code> will compile successfully if and only if <code>EXPR</code>
is nonzero.</p>

<p>Where appropriate, testsuite entries should include comments giving
their origin: the people who added them or submitted the bug report
they relate to, possibly with a reference to a PR in our bug tracking
system.  There are <a
href="https://gcc.gnu.org/ml/gcc/2000-01/msg00593.html">some copyright
guidelines</a> on what can be included in the testsuite.</p>

<p>If a testcase itself is incorrect, but there's a possibility that an
improved testcase might fail on some platform where the incorrect
testcase passed, the old testcase should be removed and a new testcase
(with a different name) should be added.  This helps automated
regression-checkers distinguish a true regression from an improvement
to the testsuite.</p>


<h2 id="Diagnostics">Diagnostics Conventions</h2>
<ul>

<li>Use of the <code>input_location</code> global, and of the
diagnostic functions that implicitly use <code>input_location</code>,
is deprecated; the preferred technique is to pass around locations
ultimately derived from the location of some explicitly chosen source
code token.</li>

<li>Diagnostics using the GCC diagnostic functions should generally
use the GCC-specific formats such as <code>%qs</code> or
<code>%&lt;</code> and <code>%&gt;</code> for quoting and
<code>%m</code> for <code>errno</code> numbers.</li>

<li>Identifiers should generally be formatted with <code>%E</code> or
<code>%qE</code>; use of <code>identifier_to_locale</code> is needed
if the identifier text is used directly.</li>

<li>Formats such as <code>%wd</code> should be used with types such as
<code>HOST_WIDE_INT</code> (<code>HOST_WIDE_INT_PRINT_DEC</code> is a
format for the host <code>printf</code> functions, not for the GCC
diagnostic functions).</li>

<li><code>error</code> is for defects in the user's code.</li>

<li><code>sorry</code> is for correct user input programs but
unimplemented functionalities.</li>

<li><code>warning</code> is for advisory diagnostics; it
may be used for diagnostics that have severity less than an
error.</li>

<li><code>inform</code> is for adding additional explanatory
information to a diagnostic.</li>

<li><code>internal_error</code> is used for conditions that should not
be triggered by any user input whether valid or invalid and including
invalid asms and LTO binary data (sometimes, as an exception, there is
a call to <code>error</code> before further information is printed and
an ICE is triggered).  Assertion failures should not be triggered by
invalid input.</li>

<li><code>inform</code> is for informative notes accompanying errors
and warnings.</li>

<li>All diagnostics should be full sentences without English
fragments substituted in them, to facilitate translation.</li>

</ul>


<h2 id="Spelling">Spelling, terminology and markup</h2>

<p>The following conventions of spelling and terminology apply
throughout GCC, including the manuals, web pages, diagnostics,
comments, and (except where they require spaces or hyphens to be used)
function and variable names, although consistency in user-visible
documentation and diagnostics is more important than that in comments
and code.  The following table lists some simple cases:</p>

<table class="padding5">
  <tr>
    <th>Use...</th><th>...instead of</th><th>Rationale</th>
  </tr>
  <tr>
    <td>American spelling (in particular -ize, -or)</td>
    <td>British spelling (in particular -ise, -our)</td>
    <td></td>
  </tr>
  <tr>
    <td>"32-bit" (adjective)</td>
    <td>"32 bit"</td>
    <td></td>
  </tr>
  <tr>
    <td>"alphanumeric"</td>
    <td>"alpha numeric"</td>
    <td></td>
  </tr>
  <tr>
    <td>"back end" (noun)</td>
    <td>"back-end" or "backend"</td>
    <td></td>
  </tr>
  <tr>
    <td>"back-end" (adjective)</td>
    <td>"back end" or "backend"</td>
    <td></td>
  </tr>
  <tr>
    <td>"bit-field"</td>
    <td>"bit field" or "bitfield"</td>
    <td>Spelling used in C and C++ standards</td>
  </tr>
  <tr>
    <td>"built-in" as an adjective ("built-in function") or "built in"</td>
    <td>"builtin"</td>
    <td>"builtin" isn't a word</td>
  </tr>
  <tr>
    <td>"bug fix" (noun) or "bug-fix" (adjective)</td>
    <td>"bugfix" or "bug-fix"</td>
    <td>"bugfix" isn't a word</td>
  </tr>
  <tr>
    <td>"ColdFire"</td>
    <td>"coldfire" or "Coldfire"</td>
    <td></td>
  </tr>
  <tr>
    <td>"command-line option"</td>
    <td>"command line option"</td>
    <td></td>
  </tr>
  <tr>
    <td>"compilation time" (noun);
      how long it takes to compile the program</td>
    <td>"compile time"</td>
    <td></td>
  </tr>
  <tr>
    <td>"compile time" (noun), "compile-time" (adjective);
      the time at which the program is compiled</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>"dependent" (adjective), "dependence", "dependency"</td>
    <td>"dependant", "dependance", "dependancy"</td>
    <td></td>
  </tr>
  <tr>
    <td>"enumerated"</td>
    <td>"enumeral"</td>
    <td>Terminology used in C and C++ standards</td>
  </tr>
  <tr>
    <td>"epilogue"</td>
    <td>"epilog"</td>
    <td>Established convention</td>
  </tr>
  <tr>
    <td>"execution time" (noun);
      how long it takes the program to run</td>
    <td>"run time" or "runtime"</td>
    <td></td>
  </tr>
  <tr>
    <td>"floating-point" (adjective)</td>
    <td>"floating point"</td>
    <td></td>
  </tr>
  <tr>
    <td>"free software" or just "free"</td>
    <td>"Open Source" or "OpenSource"</td>
    <td></td>
  </tr>
  <tr>
    <td>"front end" (noun)</td>
    <td>"front-end" or "frontend"</td>
    <td></td>
  </tr>
  <tr>
    <td>"front-end" (adjective)</td>
    <td>"front end" or "frontend"</td>
    <td></td>
  </tr>
  <tr>
    <td>"GNU/Linux" (except in reference to the kernel)</td>
    <td>"Linux" or "linux" or "Linux/GNU"</td>
    <td></td>
  </tr>
  <tr>
    <td>"link time" (noun), "link-time" (adjective);
      the time at which the program is linked</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>"lowercase"</td>
    <td>"lower case" or "lower-case"</td>
    <td></td>
  </tr>
  <tr>
    <td>"H8S"</td>
    <td>"H8/S"</td>
    <td></td>
  </tr>
  <tr>
    <td>"Microsoft Windows"</td>
    <td>"Windows"</td>
    <td></td>
  </tr>
  <tr>
    <td>"MIPS"</td>
    <td>"Mips" or "mips"</td>
    <td></td>
  </tr>
  <tr>
    <td>"nonzero"</td>
    <td>"non-zero" or "non zero"</td>
    <td></td>
  </tr>
  <tr>
    <td>"null character"</td>
    <td>"zero character"</td>
    <td></td>
  </tr>
  <tr>
    <td>"Objective-C"</td>
    <td>"Objective C"</td>
    <td></td>
  </tr>
  <tr>
    <td>"prologue"</td>
    <td>"prolog"</td>
    <td>Established convention</td>
  </tr>
  <tr>
    <td>"PowerPC"</td>
    <td>"powerpc", "powerPC" or "PowerPc"</td>
    <td></td>
  </tr>
  <tr>
    <td>"Red Hat"</td>
    <td>"RedHat" or "Redhat"</td>
    <td></td>
  </tr>
  <tr>
    <td>"return type" (noun), "return value" (noun)</td>
    <td>"return-type", "return-value"</td>
    <td></td>
  </tr>
  <tr>
    <td>"run time" (noun), "run-time" (adjective);
      the time at which the program is run</td>
    <td>"runtime"</td>
    <td></td>
  </tr>
  <tr>
    <td>"runtime" (both noun and adjective);
      libraries and system support present at run time</td>
    <td>"run time", "run-time"</td>
    <td></td>
  </tr>
  <tr>
    <td>"SPARC"</td>
    <td>"Sparc" or "sparc"</td>
    <td></td>
  </tr>
  <tr>
    <td>"testcase", "testsuite"</td>
    <td>"test-case" or "test case", "test-suite" or "test suite"</td>
    <td></td>
  </tr>
  <tr>
    <td>"uppercase"</td>
    <td>"upper case" or "upper-case"</td>
    <td></td>
  </tr>
  <tr>
    <td>"VAX", "VAXen", "MicroVAX"</td>
    <td>"vax" or "Vax", "vaxen" or "vaxes", "microvax" or "microVAX"</td>
    <td></td>
  </tr>
</table>

<p>"GCC" should be used for the GNU Compiler Collection, both
generally and as the GNU C Compiler in the context of compiling C;
"G++" for the C++ compiler; "gcc" and "g++" (lowercase), marked up
with <code>@command</code> when in Texinfo, for the commands for
compilation when the emphasis is on those; "GNU C" and "GNU C++" for
language dialects; and try to avoid the older term "GNU CC".</p>

<p>Use a comma after "e.g." or "i.e." if and only if it is appropriate
in the context and the slight pause a comma means helps the reader; do
not add them automatically in all cases just because some style guides
say so.  (In Texinfo manuals, <code>@:</code> should to be used after
"e.g." and "i.e." when a comma isn't used.)</p>

<p>In Texinfo manuals, Texinfo 4.0 features may be used, and should be
used where appropriate.  URLs should be marked up with
<code>@uref</code>; email addresses with <code>@email</code>;
command-line options with <code>@option</code>; names of commands with
<code>@command</code>; environment variables with <code>@env</code>.
NULL should be written as <code>@code{NULL}</code>.  Tables of
contents should come just after the title page; printed manuals will
be formatted (for example, by <code>make dvi</code>) using
<code>texi2dvi</code> which reruns TeX until cross-references
stabilize, so there is no need for a table of contents to go at the
end for it to have correct page numbers.  The <code>@refill</code>
feature is obsolete and should not be used.  All manuals should use
<code>@dircategory</code> and <code>@direntry</code> to provide Info
directory information for <code>install-info</code>.</p>

<p>It is useful to read the <a
href="http://www.gnu.org/software/texinfo/manual/texinfo/">Texinfo manual</a>.
Some general Texinfo style issues discussed in that manual should be
noted:</p>

<ul>

  <li>For proper formatting of the printed manual, TeX quotes (matched
  <code>`</code> or <code>``</code> and <code>'</code> or
  <code>''</code>) should be used; neutral ASCII double quotes
  (<code>"..."</code>) should not be.  Similarly, TeX dashes
  (<code>--</code> (two hyphens) for an en dash and <code>---</code>
  (three hyphens) for an em dash) should be used; normally these
  dashes should not have whitespace on either side.  Minus signs
  should be written as <code>@minus{}</code>.</li>

  <li>For an ellipsis, <code>@dots{}</code> should be used; for a
  literal sequence of three dots in a programming language, the dots
  should be written as such (<code>...</code>) rather than as
  <code>@dots{}</code>.</li>

  <li>English text in programming language comments in examples should
  be enclosed in <code>@r{}</code> so that it is printed in a
  non-fixed-width font.</li>

  <li>Full stops that end sentences should be
  followed by two spaces or by end of line.  Full
  stops that are preceded by a lower-case letter but do not end a
  sentence should be followed by <code>@:</code> if they are not
  followed by other punctuation such as a comma; full stops, question
  marks and exclamation marks that end a sentence but are preceded by
  an upper-case letter should be written as "<code>@.</code>",
  "<code>@?</code>" and "<code>@!</code>", respectively.  (This is not
  required if the capital letter is within <code>@code</code> or
  <code>@samp</code>.)</li>

  <li>Use <code>@code</code> for an expression in a program, for the name
  of a variable or function used in a program, or for a keyword in
  a programming language.  However, avoid <code>@code</code> in uses
  of language keywords as adjectives.  For example, appropriate uses
  of <code>@code</code> are in phrases such as
  <i>"<code>@code{const}</code>-qualified type"</i>, or
  <i>"<code>@code{asm}</code> statement"</i>, or
  <i>"function returns <code>@code{true}</code></i>".
  Examples where <code>@code</code> should be avoided are phrases such as
  <i>"const variable"</i>, <i>"volatile access"</i>, or
  <i>"condition is false."</i></li>
</ul>


<h2 id="upstream">Upstream packages</h2>

<p>Some files and packages in the GCC source tree are imported from
elsewhere, and we want to minimize divergence from their upstream sources.
The following files should be updated only according to the rules set
below:</p>

<ul>

<li>config.guess, config.sub: Instructions for getting the master copy
of these files is
at <a href="https://ftp.gnu.org/pub/gnu/config/">https://ftp.gnu.org/pub/gnu/config</a>.
Proposed changes should be e-mailed
to <a href="mailto:config-patches@gnu.org">config-patches@gnu.org</a>.
Only after the change makes it to the HTTP site should the new files
be installed in the GCC source tree, so that their version numbers
remain meaningful and unique.  Don't install the patch, install the
whole file.</li>

<li>ltmain.sh, libtool.m4, ltoptions.m4, ltsugar.m4, ltversion.m4,
lt~obsolete.m4, and formerly also ltconfig, ltcf-c.sh, ltcf-cxx.sh,
ltcf-gcj.sh: The master copy of these files is the source repository of
<a href="http://www.gnu.org/software/libtool/libtool.html">GNU
libtool</a>.  Patches should be posted to <a
href="mailto:libtool-patches@gnu.org">libtool-patches@gnu.org</a>.
Only after the change makes it to the libtool source tree should the new
files be installed in the GCC source tree.<br />
ltgcc.m4 is not imported from upstream.<br />
ltconfig and ltmain.sh are generated files from ltconfig.in and
ltmain.in, respectively, and with libtool 2.1, the latter is generated
from ltmain.m4sh, so, when you post the patch, make sure you're
patching the source file, not the generated one.  When you update
these generated files in the GCC repository, make sure they report the
same timestamp and version number, and note this version number in the
ChangeLog.</li>

<li>Top-level configure.ac, configure, Makefile.in, config-ml.in,
config.if and most other top-level shell-scripts: Please try to keep
these files in sync with the corresponding files in the src repository
at sourceware.org.  Some people hope to eventually merge these
trees into a single repository; keeping them in sync helps this goal.
When you check in a patch to one of these files, please check it in
the src tree too, or ask someone else with write access there to
do so.</li>

<li>Top-level compile, depcomp, install-sh, missing, mkinstalldirs,
symlink-tree and ylwrap:  These are copied from mainline automake, using
<code>automake --add-missing --copy --force-missing</code>.</li>

<li>move-if-change:  gnulib hosts this now.  The latest version can be
retrieved from
<a href="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/move-if-change">http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/move-if-change</a>.
</li>

<li>Top-level config.rpath:  This comes originally from gettext, but
gnulib can be considered upstream.  The latest version can be retrieved
from
<a href="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/config.rpath">http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/config.rpath</a>.
Contents should be kept in sync with relevant parts of libtool.m4 from
Libtool.</li>

<li>gcc/doc/include/texinfo.tex: This file is copied from texinfo,
the latest version is at
<a href="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/texinfo.tex">http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/texinfo.tex</a>.</li>

<li>gcc/config/soft-fp: The master sources (except for
<code>t-softfp</code>) are in git glibc, and changes should go there
before going into GCC.</li>

<li>fastjar: The master sources were at <a
href="http://fastjar.sourceforge.net/">fastjar.sourceforge.net</a>.
However, the upstream source seems to be dead, so fastjar is
essentially maintained in the GCC source tree.</li>

<li>boehm-gc: The master sources are at <a
href="https://hboehm.info/gc/">http://hboehm.info/gc/</a>.
Patches should be sent to
<a href="mailto:bdwgc@lists.opendylan.org">bdwgc@lists.opendylan.org</a>,
but it's acceptable to check them in the GCC source tree before getting
them installed in the master tree.</li>

<li>zlib: The master sources come from
<a href="http://www.zlib.net/">zlib.net</a>.  However, the
autoconf-based configury is a local GCC invention.  Changes to zlib
outside the build system are discouraged, and should be sent upstream
first. </li>

<li>libstdc++-v3:  In docs/doxygen, comments in *.cfg.in are
partially autogenerated from <a href="https://www.doxygen.nl">the
Doxygen tool</a>.  In docs/html, the ext/lwg-* files are copied from <a
href="http://www.open-std.org/jtc1/sc22/wg21/">the C++ committee homepage</a>,
the 27_io/binary_iostream_* files are copies of Usenet postings, and most
of the files in 17_intro are either copied from elsewhere in GCC or the
FSF website, or are autogenerated.  These files should not be changed
without prior permission, if at all.</li>

<li>libgcc/config/libbid: The master sources come from Intel BID library
<a href="http://www.netlib.org/misc/intel/">Intel BID library</a>. 
Bugs should be reported to
<a href="mailto:marius.cornea@intel.com">marius.cornea@intel.com</a>
and
<a href="mailto:hongjiu.lu@intel.com">hongjiu.lu@intel.com</a>.
Changes to libbid outside the build system are discouraged, and should be
sent upstream first. </li>

</ul>


<h2 id="CandCxx">C and C++ Language Conventions</h2>

<p>
The following conventions apply to both C and C++.
</p>


<h3 id="C_Options">Compiler Options</h3>

<p>
The compiler must build cleanly with <code>-Wall -Wextra</code>.
</p>


<h3 id="C_Language">Language Use</h3>


<h4 id="Assertions">Assertions</h4>

<p>Code should use <code>gcc_assert (EXPR)</code> to check invariants.
Use <code>gcc_unreachable ()</code> to mark places that should never be
reachable (such as an unreachable <code>default</code> case of a
switch).  Do not use <code>gcc_assert (0)</code> for such purposes, as
<code>gcc_unreachable</code> gives the compiler more information.  The
assertions are enabled unless explicitly configured off with
<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
User input should never be validated by either <code>gcc_assert</code>
or <code>gcc_unreachable</code>.  If the checks are expensive or the
compiler can reasonably carry on after the error, they may be
conditioned on <code>--enable-checking</code>
by using <code>gcc_checking_assert</code>.</p>


<h4 id="Character">Character Testing</h4>

<p>Code testing properties of characters from user source code should
use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
instead of the standard functions such as <code>isalpha</code> from
<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
language accepted.</p>


<h4 id="Error">Error Node Testing</h4>

<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
against <code>error_mark_node</code> rather than by comparing the
<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
href="https://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>


<h4 id="Generated">Parameters Affecting Generated Code</h4>

<p>Internal numeric parameters that may affect generated code should
be controlled by <code>--param</code> rather than being hardcoded.</p>


<h4 id="C_Inlining">Inlining Functions</h4>

<p>
Inlining functions only when
you have reason to believe that
the expansion of the function is smaller than a call to the function
or that inlining is significant to the run-time of the compiler.
</p>


<h3 id="C_Formatting">Formatting Conventions</h3>


<h4 id="Line">Line Length</h4>

<p>Lines shall be at most 80 columns.</p>


<h4 id="C_Names">Names</h4>

<p>
Macros names should be in <code>ALL_CAPS</code>
when it's important to be aware that it's a macro
(e.g. accessors and simple predicates),
but in lowercase (e.g., <code>size_int</code>)
where the macro is a wrapper for efficiency
that should be considered as a function;
see messages
<a href="https://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
and <a href="https://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.
</p>

<p>
Other names should be lower-case and separated by low_lines.
</p>


<h4 id="Expressions">Expressions</h4>

<p>
Code in GCC should use the following formatting conventions:
</p>

<table class="padding5">
<tr>
  <th class="left">For</th>
  <th class="right">Use...</th>
  <th class="left">...instead of</th>
</tr>
<tr>
  <td class="left">logical not</td>
  <td class="right"><code>!x</code></td>
  <td><code>! x</code></td>
</tr>
<tr>
  <td class="left">bitwise complement</td>
  <td class="right"><code>~x</code></td>
  <td><code>~ x</code></td>
</tr>
<tr>
  <td class="left">unary minus</td>
  <td class="right"><code>-x</code></td>
  <td><code>- x</code></td>
</tr>
<tr>
  <td class="left">cast</td>
  <td class="right"><code>(type) x</code></td>
  <td><code>(type)x</code></td>
</tr>
<tr>
  <td class="left">pointer cast</td>
  <td class="right"><code>(type *) x</code></td>
  <td><code>(type*)x</code></td>
</tr>
<tr>
  <td class="left">pointer return type</td>
  <td class="right"><code>type *f (void)</code></td>
  <td><code>type* f (void)</code></td>
</tr>
<tr>
  <td class="left">pointer dereference</td>
  <td class="right"><code>*x</code></td>
  <td><code>* x</code></td>
</tr>
</table>


<h2 id="Cxx_Conventions">C++ Language Conventions</h2>

<p>
The following conventions apply only to C++.
</p>

<p>
These conventions will change over time,
but changing them requires a convincing rationale.
</p>


<h3 id="Cxx_Language">Language Use</h3>

<p>
C++ is a complex language,
and we strive to use it in a manner that is not surprising.
So, the primary rule is to be reasonable.
Use a language feature in known good ways.
If you need to use a feature in an unusual way,
or a way that violates the "should" rules below,
seek guidance, review and feedback from the wider community.
</p>

<p>
All use of C++ features
is subject to the decisions of the maintainers of the relevant components.
(This restates something that is always true for gcc,
which is that
component maintainers make the final decisions about those components.)
</p>

<h4 id="Variable">Variable Definitions</h4>

<p>
Variables should be defined at the point of first use,
rather than at the top of the function.
The existing code obviously does not follow that rule,
so variables may be defined at the top of the function,
as in C90.
</p>

<p>
Variables may be simultaneously defined and tested in control expressions.
</p>

<p>
<a href="codingrationale.html#variables">Rationale and Discussion</a>
</p>


<h4 id="Struct_Use">Struct Definitions</h4>

<p>
Some coding conventions, including GCC's own in the past, recommend
using the <code>struct</code> keyword (also known as the <i>class-key</i>)
for <a href="https://en.wikipedia.org/wiki/Plain_old_data_structure">
plain old data (POD)</a> types.  However, since the POD concept has been
replaced in C++ by a set of much more nuanced distinctions, the current
guidance (though not a requirement) is to use the <code>struct</code>
<i>class-key</i> when defining structures that could be used without
change in C, and use <code>class</code> for all other classes.  It is
recommended to use the same <i>class-key</i> consistently in all
declarations and, if necessary, in uses of the class.
The <code>-Wmismatched-tags</code> warning option helps detect mismatches.
The <code>-Wredundant-tags</code> GCC option further helps identify places
where the <i>class-key</i> can safely be omitted.

</p>

<p>
<a href="codingrationale.html#struct">Rationale and Discussion</a>
</p>

<h4 id="Class_Use">Class Definitions</h4>

<p>
See the guidance in <a href="#Struct_Use">Struct Definitions</a> for
the suggested choice of a <i>class-key</i>.
</p>

<p>
A class defined with the class-key <code>class</code> type will often
(but not always) ave a declaration of a
<a href="https://en.wikipedia.org/wiki/Special_member_functions">
special member function</a>.
If any one of these is declared,
then all should be either declared
or have an explicit comment saying that the default is intended.
</p>

<p>
Single inheritance is permitted.
Use public inheritance to describe interface inheritance,
i.e. 'is-a' relationships.
Use private and protected inheritance
to describe implementation inheritance.
Implementation inheritance can be expedient,
but think twice before using it in code
intended to last a long time.
</p>

<p>
Complex hierarchies are to be avoided.
Take special care with multiple inheritance.
On the rare occasion that using mulitple inheritance is indeed useful,
prepare design rationales in advance,
and take special care to make documentation of the entire hierarchy clear.
(In particular, multiple inheritance can be an acceptable way of combining
"traits"-style classes that only contain static member functions.
Its use with data-carrying classes is more problematic.)
</p>

<p>
Think carefully about the size and performance impact
of virtual functions and virtual bases
before using them.
</p>

<p>
Prefer to make data members private.
</p>

<p>
<a href="codingrationale.html#class">Rationale and Discussion</a>
</p>


<h4 id="Constructors">Constructors and Destructors</h4>

<p>
All constructors should initialize data members
in the member initializer list rather than in the body of the constructor.
</p>

<p>
A class with virtual functions or virtual bases
should have a virtual destructor.
</p>

<p>
<a href="codingrationale.html#constructors">Rationale and Discussion</a>
</p>

<h4 id="Conversions">Conversions</h4>

<p>
Single argument constructors should nearly always be declared explicit.
</p>

<p>
Conversion operators should be avoided.
</p>

<p>
<a href="codingrationale.html#conversions">Rationale and Discussion</a>
</p>


<h4 id="Over_Func">Overloading Functions</h4>

<p>
Overloading functions is permitted,
but take care to ensure that overloads are not surprising,
i.e. semantically identical or at least very similar.
Virtual functions should not be overloaded. 
</p>

<p>
<a href="codingrationale.html#overfunc">Rationale and Discussion</a>
</p>


<h4 id="Over_Oper">Overloading Operators</h4>

<p>
Overloading operators is permitted,
but take care to ensure that overloads are not surprising.
Some unsurprising uses are
in the implementation of numeric types and
in following the C++ Standard Library's conventions.
In addition, overloaded operators, excepting the call operator,
should not be used for expensive implementations.
</p>

<p>
<a href="codingrationale.html#overoper">Rationale and Discussion</a>
</p>

<p>
Note: in declarations of operator functions or in invocations of
such functions that involve the keyword <code>operator</code>,
the full name of the operator should be considered as including
the keyword with no spaces in between the keyword and the operator
token.  Thus, the expected format of a declaration of an operator
is</p><pre>
    T &amp;operator== (const T &amp; const T &amp;);
</pre>
<p>and not</p><pre>
    T &amp;operator == (const T &amp; const T &amp;);
</pre>
<p>
(with the space between <code>operator</code> and <code>==</code>).
</p>


<h4 id="Default">Default Arguments</h4>

<p>
Default arguments are another type of function overloading,
and the same rules apply.
Default arguments must always be POD values, i.e. may not run constructors.
Virtual functions should not have default arguments.
</p>

<p>
<a href="codingrationale.html#default">Rationale and Discussion</a>
</p>


<h4 id="Cxx_Inlining">Inlining Functions</h4>

<p>
Constructors and destructors, even those with empty bodies,
are often much larger than programmers expect.
Prefer non-inline versions unless you have evidence
that the inline version is smaller or has a significant performance impact.
</p>


<h4 id="Template_Use">Templates</h4>

<p>
To avoid excessive compiler size,
consider implementing non-trivial templates
on a non-template base class with <code>void*</code> parameters.
</p>


<h4 id="Namespace_Use">Namespaces</h4>

<p>
Namespaces are encouraged.
All separable libraries should have a unique global namespace.
All individual tools should have a unique global namespace.
Nested include directories names should map to nested namespaces when possible. 
</p>

<p>
Header files should have neither <code>using</code> directives
nor namespace-scope <code>using</code> declarations.
</p>

<p>
<a href="codingrationale.html#namespaces">Rationale and Discussion</a>
</p>

<h4 id="RTTI">RTTI and <code>dynamic_cast</code></h4>

<p>
Run-time type information (RTTI) is permitted
when certain non-default <code>--enable-checking</code> options are enabled,
so as to allow checkers to report dynamic types.
However, by default, RTTI is not permitted
and the compiler must build cleanly with <code>-fno-rtti</code>.
</p>

<p>
<a href="codingrationale.html#RTTI">Rationale and Discussion</a>
</p>


<h4 id="Casts">Other Casts</h4>

<p>
C-style casts should not be used.
Instead, use C++-style casts.
</p>

<p>
<a href="codingrationale.html#casts">Rationale and Discussion</a>
</p>


<h4 id="Exceptions">Exceptions</h4>

<p>
Exceptions and throw specifications are not permitted
and the compiler must build cleanly with <code>-fno-exceptions</code>.
</p>

<p>
<a href="codingrationale.html#exceptions">Rationale and Discussion</a>
</p>


<h4 id="Standard_Library">The Standard Library</h4>

<p>
Use of the standard library is permitted.
Note, however, that it is currently not usable with garbage collected data.
</p>

<p>
For compiler messages, indeed any text that needs i18n,
should continue to use the existing facilities.
</p>

<p>
For long-term code, at least for now,
we will continue to use <code>printf</code> style I/O
rather than <code>&lt;iostream&gt;</code> style I/O.
</p>

<p>
<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
</p>


<h3 id="Cxx_Formatting">Formatting Conventions</h3>


<h4 id="Cxx_Names">Names</h4>

<p>
When structs and/or classes have member functions,
prefer to name data members with a leading <code>m_</code>
and static data members with a leading <code>s_</code>.
</p>

<p>
Template parameter names should use CamelCase,
following the C++ Standard.
</p>

<p>
<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
</p>


<h4 id="Struct_Form">Struct Definitions</h4>

<p>
Note that the rules for classes do not apply to structs.
Structs continue to behave as before.
</p>


<h4 id="Class_Form">Class Definitions</h4>

<p>
If the entire class definition fits on a single line, put it on a single line.
Otherwise, use the following rules.
</p>

<p>
Do not indent protection labels.
</p>

<p>
Indent class members by two spaces.
</p>

<p>
Prefer to put the entire class head on a single line.
</p>

<blockquote><pre><code>
class gnuclass : base {
</code></pre></blockquote>

<p>
Otherwise, start the colon of the base list at the beginning of a line.
</p>

<blockquote><pre><code>
class a_rather_long_class_name 
: with_a_very_long_base_name, and_another_just_to_make_life_hard
{ 
  int member; 
};
</code></pre></blockquote>

<p>
If the base clause exceeds one line,
move overflowing initializers to the next line and indent by two spaces.
</p>

<blockquote><pre><code>
class gnuclass 
: base1 &lt;template_argument1&gt;, base2 &lt;template_argument1&gt;,
  base3 &lt;template_argument1&gt;, base4 &lt;template_argument1&gt;
{ 
  int member; 
};
</code></pre></blockquote>

<p>
When defining a class,
</p>
<ul>
<li>first define all public types,</li>
<li>then define all non-public types,</li>
<li>then declare all public constructors,</li>
<li>then declare the public destructor,</li>
<li>then declare all public member functions,</li>
<li>then declare all public member variables,</li>
<li>then declare all non-public constructors,</li>
<li>then declare the non-public destructor,</li>
<li>then declare all non-public member functions, and</li>
<li>then declare all non-public member variables.</li>
</ul>

<p>
Semantic constraints may require a different declaration order,
but seek to minimize the potential confusion.
</p>

<p>
Close a class definition
with a right brace, semicolon, optional closing comment, and a new line.
</p>

<blockquote><pre><code>
}; // class gnuclass
</code></pre></blockquote>


<h4 id="Member_Form">Class Member Definitions</h4>

<p>
Define all members outside the class definition.
That is, there are no function bodies or member initializers
inside the class definition.
</p>

<p>
Prefer to put the entire member head on a single line.
</p>

<blockquote><pre><code>
gnuclass::gnuclass () : base_class ()
{ 
  ...
};
</code></pre></blockquote>

<p>
When that is not possible,
place the colon of the initializer clause at the beginning of a line.
</p>

<blockquote><pre><code>
gnuclass::gnuclass ()
: base1 (), base2 (), member1 (), member2 (), member3 (), member4 ()
{ 
  ...
};
</code></pre></blockquote>

<p>
If the initializer clause exceeds one line,
move overflowing initializers to the next line and indent by two spaces.
</p>

<blockquote><pre><code>
gnuclass::gnuclass ()
: base1 (some_expression), base2 (another_expression),
  member1 (my_expressions_everywhere)
{ 
  ...
};
</code></pre></blockquote>

<p>
If a C++ function name is long enough
to cause the first function parameter with its type to exceed 80 characters,
it should appear on the next line indented four spaces. 
</p>

<blockquote><pre><code>
void
very_long_class_name::very_long_function_name (
    very_long_type_name arg)
{
</code></pre></blockquote>

<p>
Sometimes the class qualifier and function name together exceed 80 characters.
In this case, break the line before the <code>::</code> operator.
We may wish to do so pre-emptively for all class member functions. 
</p>

<blockquote><pre><code>
void
very_long_template_class_name &lt;with, a, great, many, arguments&gt;
::very_long_function_name (
    very_long_type_name arg)
{
</code></pre></blockquote>


<h4 id="Template_Form">Templates</h4>

<p>
A declaration following a template parameter list
should not have additional indentation.
</p>

<p>
Prefer <code>typename</code> over <code>class</code>
in template parameter lists.
</p>


<h4 id="ExternC">Extern "C"</h4>

<p>
Prefer an <code>extern "C"</code> block to a declaration qualifier.
</p>

<p>
Open an <code>extern "C"</code> block with the left brace on the same line.
</p>

<blockquote><pre><code>
extern "C" {
</code></pre></blockquote>

<p>
Close an <code>extern "C"</code> block
with a right brace, optional closing comment, and a new line.
</p>

<blockquote><pre><code>
} // extern "C"
</code></pre></blockquote>

<p>
Definitions within the body of an <code>extern "C"</code> block are not indented.
</p>

<h4 id="Namespace_Form">Namespaces</h4>

<p>
Open a namespace with the namespace name
followed by a left brace and a new line.
</p>

<blockquote><pre><code>
namespace gnutool {
</code></pre></blockquote>

<p>
Close a namespace
with a right brace, optional closing comment, and a new line.
</p>

<blockquote><pre><code>
} // namespace gnutool
</code></pre></blockquote>

<p>
Definitions within the body of a namespace are not indented.
</p>


</body>
</html>
